Dostosuj powiadomienia o multimediach i elementy sterujące odtwarzaniem za pomocą interfejsu Media Session API

Jak integrować się z klawiszami sprzętowymi do multimediów, dostosowywać powiadomienia multimedialne i wykonywać inne czynności.

François Beaufort

Aby umożliwić użytkownikom wyświetlanie informacji o tym, co jest obecnie odtwarzane w przeglądarce, oraz sterowanie odtwarzaniem bez konieczności powrotu do strony, z której zostało uruchomione, wprowadziliśmy interfejs Media Session API. Umożliwia ona programistom stron internetowych dostosowywanie tych funkcji za pomocą metadanych w niestandardowych powiadomieniach multimedialnych, zdarzeń multimedialnych, takich jak odtwarzanie, wstrzymywanie, przewijanie, zmienianie utworu, czy zdarzeń konferencji wideo, takich jak wyciszanie/wyciszanie mikrofonu, włączanie/wyłączanie kamery i rozłączanie. Te opcje są dostępne w wielu kontekstach, takich jak panele mediów na komputerze, powiadomienia o mediach na urządzeniach mobilnych, a nawet na urządzeniach noszonych. W tym artykule opiszę te opcje.

Informacje o interfejsie Media Session API

Interfejs Media Session API zapewnia kilka korzyści i możliwości:

• Obsługiwane są klucze sprzętowe.
• Powiadomienia o multimediach są dostosowywane na urządzeniach mobilnych, komputerach i sparowanych urządzeniach noszonych.
• Centrum multimediów jest dostępne na komputerze.
• Elementy sterujące multimediami na ekranie blokady są dostępne na ChromeOS i urządzeniach mobilnych.
• Elementy sterujące oknem obrazu w obrazie są dostępne w przypadku odtwarzania dźwięku, wideokonferencji i prezentacji slajdów.
• Integracja z Asystentem jest dostępna na urządzeniach mobilnych.

Poniżej przedstawiamy kilka przykładów, które pokazują, jak to działa.

Przykład 1: jeśli użytkownicy nacisną klawisz multimedialny „następny utwór” na klawiaturze, deweloperzy internetowi mogą obsłużyć to działanie niezależnie od tego, czy przeglądarka jest na pierwszym czy drugim planie.

Przykład 2: jeśli użytkownicy słuchają podcastu w internecie, gdy ekran urządzenia jest zablokowany, nadal mogą kliknąć ikonę „przewiń do tyłu” w elementach sterujących multimediów na ekranie blokady, aby deweloperzy internetowi przesunęli czas odtwarzania o kilka sekund do tyłu.

Przykład 3. Jeśli użytkownicy mają karty z odtwarzanym dźwiękiem, mogą łatwo zatrzymać odtwarzanie z poziomu panelu multimediów na komputerze. Dzięki temu deweloperzy stron internetowych mogą wyczyścić stan.

Przykład 4. Jeśli użytkownicy prowadzą rozmowę wideo, mogą w oknie Picture-in-Picture kliknąć przełącznik mikrofonu, aby strona internetowa przestała otrzymywać dane z mikrofonu.

Wszystko to można zrobić w 2 różnych interfejsach: MediaSession i MediaMetadata. Pierwszy pozwala użytkownikom kontrolować odtwarzane treści. Druga kwestia to sposób, w jaki MediaSession informujesz, co ma być kontrolowane.

Poniżej przedstawiamy, jak te interfejsy są powiązane z określonymi elementami sterowania multimediami, w tym przypadku powiadomieniem multimedialnym na urządzeniu mobilnym.

Informowanie użytkowników, co jest odtwarzane

Gdy witryna odtwarza dźwięk lub wideo, użytkownicy automatycznie otrzymują powiadomienia o multimediach w panelu powiadomień na urządzeniu mobilnym lub w centrum multimediów na komputerze. Przeglądarka stara się wyświetlać odpowiednie informacje, korzystając z tytułu dokumentu i największego znalezionego obrazu ikony. Dzięki interfejsowi API sesji multimediów można dostosować powiadomienie multimedialne, korzystając z bardziej rozbudowanych metadanych multimediów, takich jak tytuł, nazwa wykonawcy, nazwa albumu i okładka, jak pokazano poniżej.

Chrome prosi o „pełne” skupienie na dźwięku, aby wyświetlać powiadomienia o multimediach tylko wtedy, gdy czas trwania multimediów wynosi co najmniej 5 sekund. Dzięki temu przypadkowe dźwięki, takie jak dzwonek, nie będą wyświetlać powiadomień.

// After media (video or audio) starts playing
await document.querySelector("video").play();

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    album: 'Whenever You Need Somebody',
    artwork: [
      { src: 'https://via.placeholder.com/96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/192', sizes: '192x192', type: 'image/png' },
      { src: 'https://via.placeholder.com/256', sizes: '256x256', type: 'image/png' },
      { src: 'https://via.placeholder.com/384', sizes: '384x384', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  });

  // TODO: Update playback state.
}

Po zakończeniu odtwarzania nie musisz „zwalniać” sesji multimediów, ponieważ powiadomienie zniknie automatycznie. Pamiętaj jednak, że podczas następnego odtwarzania będzie używany adres navigator.mediaSession.metadata. Dlatego ważne jest, aby zaktualizować go, gdy zmieni się źródło odtwarzania multimediów, aby mieć pewność, że w powiadomieniu o multimediach będą wyświetlane odpowiednie informacje.

Oto kilka informacji na temat metadanych multimediów.

• Tablica danych obrazów powiadomienia obsługuje adresy URL typu blob: i data:.
• Jeśli nie zdefiniujesz grafiki, a w odpowiednim rozmiarze jest obraz ikony (określony za pomocą atrybutu <link rel=icon>), powiadomienia multimedialne będą go używać.
• Docelowy rozmiar grafiki powiadomienia w Chrome na Androida to 512x512. W przypadku urządzeń niskiej klasy jest to 256x256.
• Atrybut title elementu HTML multimediów jest używany w widżecie „Obecnie odtwarzane” w macOS.
• Jeśli zasób multimedialny jest umieszczony (np. w ramce iframe), informacje z interfejsu Media Session API należy ustawić z ramy. Zobacz fragment kodu poniżej.

<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

Do metadanych multimediów możesz też dodać informacje o poszczególnych rozdziałach, takie jak tytuł sekcji, jej sygnatura czasowa i zrzut ekranu. Dzięki temu użytkownicy mogą poruszać się po treściach multimediów.

navigator.mediaSession.metadata = new MediaMetadata({
  // title, artist, album, artwork, ...
  chapterInfo: [{
    title: 'Chapter 1',
    startTime: 0,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }, {
    title: 'Chapter 2',
    startTime: 42,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }]
});

Pozwalanie użytkownikom na kontrolowanie odtwarzania

Działanie sesji multimediów to działanie (np. „odtwórz” lub „zatrzymaj”), które witryna może wykonać dla użytkowników, gdy ci wchodzą w interakcję z bieżącym odtwarzaniem multimediów. Działania są podobne do zdarzeń i działają w podobny sposób. Podobnie jak zdarzenia, działania są implementowane przez ustawienie modułów obsługi na odpowiednim obiekcie, w tym przypadku na obiekcie MediaSession. Niektóre działania są wywoływane, gdy użytkownicy naciskają przyciski zestawu słuchawkowego, innego urządzenia zdalnego, klawiatury lub wchodzą w interakcję z powiadomieniem multimedialnym.

Ponieważ niektóre działania dotyczące sesji multimedialnej mogą nie być obsługiwane, zalecamy użycie bloku try…catch podczas ich konfigurowania.

const actionHandlers = [
  ['play',          () => { /* ... */ }],
  ['pause',         () => { /* ... */ }],
  ['previoustrack', () => { /* ... */ }],
  ['nexttrack',     () => { /* ... */ }],
  ['stop',          () => { /* ... */ }],
  ['seekbackward',  (details) => { /* ... */ }],
  ['seekforward',   (details) => { /* ... */ }],
  ['seekto',        (details) => { /* ... */ }],
  /* Video conferencing actions */
  ['togglemicrophone', () => { /* ... */ }],
  ['togglecamera',     () => { /* ... */ }],
  ['hangup',           () => { /* ... */ }],
  /* Presenting slides actions */
  ['previousslide', () => { /* ... */ }],
  ['nextslide',     () => { /* ... */ }],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

Wyłączenie modułu obsługi działania sesji multimedialnej jest tak proste jak ustawienie go na null.

try {
  // Unset the "nexttrack" action handler at the end of a playlist.
  navigator.mediaSession.setActionHandler('nexttrack', null);
} catch (error) {
  console.log(`The media session action "nexttrack" is not supported yet.`);
}

Po ustawieniu moduły obsługi czynności sesji multimediów będą działać podczas odtwarzania multimediów. Jest to podobne do wzorca odbiornika zdarzeń, z tym że obsługa zdarzenia oznacza, że przeglądarka przestaje wykonywać jakiekolwiek domyślne działania i traktuje to jako sygnał, że witryna obsługuje działanie związane z multimediami. Dlatego elementy sterujące działaniem multimediów nie będą widoczne, dopóki nie ustawisz odpowiedniego modułu obsługi.

Odtwarzanie / wstrzymywanie

Działanie "play" wskazuje, że użytkownik chce wznowić odtwarzanie multimediów, a "pause" wskazuje na chęć tymczasowego zatrzymania odtwarzania.

Ikona „odtwórz/wstrzymaj” jest zawsze wyświetlana w powiadomieniu o multimediach, a powiązane z nim zdarzenia multimedialne są obsługiwane automatycznie przez przeglądarkę. Aby zastąpić domyślne działanie, obsłuż akcje „odtwórz” i „wstrzymaj” w mediach, jak pokazano poniżej.

Podczas przewijania lub wczytywania przeglądarka może uznać, że strona internetowa nie odtwarza multimediów. W tym przypadku możesz zmienić to zachowanie, ustawiając wartość navigator.mediaSession.playbackState na "playing" lub "paused", aby interfejs witryny był zsynchronizowany z elementami sterującymi powiadomieniami o mediach.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('play', async () => {
  // Resume playback
  await video.play();
});

navigator.mediaSession.setActionHandler('pause', () => {
  // Pause active playback
  video.pause();
});

video.addEventListener('play', () => {
  navigator.mediaSession.playbackState = 'playing';
});

video.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
});

Poprzedni utwór

Działanie "previoustrack" wskazuje, że użytkownik chce rozpocząć odtwarzanie bieżącego multimediów od początku, jeśli odtwarzanie ma charakter początkowy, lub przejść do poprzedniego elementu na playliście, jeśli odtwarzanie ma charakter playlisty.

navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Play previous track.
});

Następny utwór

Działanie "nexttrack" wskazuje, że użytkownik chce przenieść odtwarzanie multimediów do następnego elementu na playliście, jeśli odtwarzanie multimediów ma pojęcie playlisty.

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Play next track.
});

Zatrzymaj

Działanie "stop" wskazuje, że użytkownik chce zatrzymać odtwarzanie multimediów i w odpowiednim przypadku wyczyścić stan.

navigator.mediaSession.setActionHandler('stop', () => {
  // Stop playback and clear state if appropriate.
});

Przewijanie do tyłu / do przodu

Działanie "seekbackward" wskazuje, że użytkownik chce przesunąć czas odtwarzania multimediów o krótki okres w tył, a działanie "seekforward" wskazuje, że użytkownik chce przesunąć czas odtwarzania multimediów o krótki okres do przodu. W obu przypadkach krótki okres to kilka sekund.

Wartość seekOffset podana w obiekcie obsługi działania to czas w sekundach, o który przesuwa się czas odtwarzania multimediów. Jeśli nie podano wartości (np. undefined), należy użyć rozsądnego czasu (np. 10–30 sekund).

const video = document.querySelector('video');
const defaultSkipTime = 10; /* Time to skip in seconds by default */

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.max(video.currentTime - skipTime, 0);
  // TODO: Update playback state.
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
  // TODO: Update playback state.
});

Przewijanie do określonego momentu

Działanie "seekto" wskazuje, że użytkownik chce przesunąć czas odtwarzania multimediów do określonego momentu.

Wartość seekTime podana w obiekcie obsługi działania to czas w sekundach, o który przesunąć odtwarzanie multimediów.

Argument logiczny fastSeek podany w obiekcie obsługującym działanie ma wartość true, jeśli działanie jest wywoływane wielokrotnie w ramach sekwencji i nie jest to ostatnie wywołanie w tej sekwencji.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in video) {
    // Only use fast seek if supported.
    video.fastSeek(details.seekTime);
    return;
  }
  video.currentTime = details.seekTime;
  // TODO: Update playback state.
});

Ustawianie pozycji odtwarzania

Dokładne wyświetlanie pozycji odtwarzania multimediów w powiadomieniu jest tak samo proste jak ustawienie stanu pozycji we właściwym momencie, jak pokazano poniżej. Stan pozycji to kombinacja szybkości odtwarzania multimediów, czasu trwania i bieżącego czasu.

Czas trwania musi być podany i dodatni. Pozycja musi być dodatnia i mniejsza niż czas trwania. Szybkość odtwarzania musi być większa niż 0.

const video = document.querySelector('video');

function updatePositionState() {
  if ('setPositionState' in navigator.mediaSession) {
    navigator.mediaSession.setPositionState({
      duration: video.duration,
      playbackRate: video.playbackRate,
      position: video.currentTime,
    });
  }
}

// When video starts playing, update duration.
await video.play();
updatePositionState();

// When user wants to seek backward, update position.
navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek forward, update position.
navigator.mediaSession.setActionHandler('seekforward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek to a specific time, update position.
navigator.mediaSession.setActionHandler('seekto', (details) => {
  /* ... */
  updatePositionState();
});

// When video playback rate changes, update position state.
video.addEventListener('ratechange', (event) => {
  updatePositionState();
});

Zresetowanie stanu pozycji jest tak proste jak ustawienie go na null.

// Reset position state when media is reset.
navigator.mediaSession.setPositionState(null);

Czynności związane z rozmowami wideo

Gdy użytkownik przełączy rozmowę wideo do okna obrazu w obrazie, przeglądarka może wyświetlić elementy sterujące mikrofonem i kamerą oraz opcję rozłączenia. Gdy użytkownik kliknie te opcje, witryna przeprowadzi go do działań związanych z wideokonferencjami opisanych poniżej. Przykładem jest rozmowa wideo.

Włącz lub wyłącz mikrofon

Działanie "togglemicrophone" wskazuje, że użytkownik chce wyciszyć lub włączyć mikrofon. Metoda setMicrophoneActive(isActive) informuje przeglądarkę, czy witryna uważa, że mikrofon jest obecnie aktywny.

let isMicrophoneActive = false;

navigator.mediaSession.setActionHandler('togglemicrophone', () => {
  if (isMicrophoneActive) {
    // Mute the microphone.
  } else {
    // Unmute the microphone.
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

Przełącz aparat

Działanie "togglecamera" wskazuje, że użytkownik chce włączyć lub wyłączyć aktywną kamerę. Metoda setCameraActive(isActive) wskazuje, czy przeglądarka uważa, że strona jest aktywna.

let isCameraActive = false;

navigator.mediaSession.setActionHandler('togglecamera', () => {
  if (isCameraActive) {
    // Disable the camera.
  } else {
    // Enable the camera.
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

rozłączyć połączenie,

Działanie "hangup" wskazuje, że użytkownik chce zakończyć połączenie.

navigator.mediaSession.setActionHandler('hangup', () => {
  // End the call.
});

Działanie podczas wyświetlania slajdów

Gdy użytkownik umieści prezentację slajdów w oknie Picture-in-Picture, przeglądarka może wyświetlić elementy sterujące do poruszania się po slajdach. Gdy użytkownik kliknie te linki, witryna przekieruje go do nich za pomocą interfejsu Media Session API. Przykładem jest prezentacja slajdów.

Poprzedni slajd

Działanie "previousslide" wskazuje, że użytkownik chce wrócić do poprzedniej slajdu podczas prezentacji.

navigator.mediaSession.setActionHandler('previousslide', () => {
  // Show previous slide.
});

Następny slajd

Działanie "nextslide" wskazuje, że użytkownik chce przejść do następnego slajdu podczas prezentacji slajdów.

navigator.mediaSession.setActionHandler('nextslide', () => {
  // Show next slide.
});

Przykłady

Zapoznaj się z przykładami sesji multimedialnej, w których wykorzystano fundację Blender i pracę Jana Morgensterna.

Zasoby

• Specyfikacja sesji multimediów: wicg.github.io/mediasession
• Problemy ze specyfikacją: github.com/WICG/mediasession/issues
• Błędy w Chrome: crbug.com